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Introducllon 

Th» MAC/65 ToolKit is *n extensiv* colltction of macros coupled with 
prtcisely written run-tim* cod* which greatly facilitates machin* languag* 
Programming on th* Atari Computer using »ither th» disk or cartridge 
Version of MAC/65. 

Th» MAC/65 ToolKit ii p»rf*ct for both th» b»ginning and th» Professional 
machin» languag* programmtr. Th» b»ginn»r will find his/h»r transition to 
machin» languag» is gr»atly simplified by th» ToolKit's BASIC-lik» Syntax. 
Th» Professional programmer will appreciat» th» time and money that th» 
ToolKit saves by providing debugged and prccisaly written cod» for most 
common Operation». Includcd on th» ToolKit diskett» ar» thre» librariss: 

XERNEL.M65 - this fil» provides: 2 byt» operations, integer math. 
IF...THBN» DO loops» ERROR handling, I/O (including multiple byt» and 
binary load>» graphics» sound and random number gencration. 

PMOR.M65 - a group of routincs which »et up playtr-missile graphics» 
mov» players» mitsiles» detect collisions» and much mor», 

8CROLL.M65 - routin*» which implcmcnt automatic screen fine scrolling 
capabilitias. 

Using Th» MAC/65 ToolKit can cut your programming tim» in half. 
Programs which previously would not hav» be»n attempted in machin» 
languag» ar» now don» »asily thanks to th» ToolKit's I/O Support and 
graphics routincs. 

Syittm R»ouir»m»nts: Th» MAC/65 ToolKit is designed for us» with 
MAC/6S on ATARI Computers with 48K of RAH or mor*. 

To Boot This Disk simply boot your DOS disk with the MAC/65 cartridg» 
inserted, and th»n put this disk in your driv*. THIS DISKETTE DOBS 
NOT HA VE DOS ON IT AND WILL NOT BOOT DIRECTLY. 

üllng Tht MAC/65 ToolKit 

Th» general proccdur» for acccssing th» ToolKit routines is to us» th» 
.INCLUDB dir«ctiv» to make th* desired ToolKit commands availabl». Aft»r 
the MAC/65 ToolKit libraries hav» b»»n included» all that is required is a 
macro call which» for th* most part, us»s Syntax similar to that of the 
•quivalcnt BASIC Statements (*g. OPEN 6,8,0,"D:FILE). It is b*st to 
indud» The ToolKit fil»s you plan to us» at the very beginning of your 
sourc» cod» as in th* following »xampl»: 

1088 JMP MYCODE 

1018 .INCLUDE 8DiK£RNEL.M65 

1020 .INCLUDE #DiPMGR.M65 

1038 MYCODE (YOUR SOURCE CODE STARTS HERE 
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Not»: KERNEL.H65 is required to rgn either PMGR.H63 or SCROLL.M65. 

The MAC/65 Tool Kit usis the following general rules: 

1 . All macro call* preserve the value of the X and Y registers. The 
value of the accumulator and »tatu5 register are» in general, uncertain 
unlei* specifically noted in the manual. 

2. All th# ToolKit global labels begin with QQ; the exceptions are the 
special labels ueed in SCROLL.M65 (See Usirtg the SCROLL.M65 Library) 
and the loop counters I,J, and K. Yog should not begin any labels in 
your code with QQ to avoid potential conflicts. 

3. Th* ToolKit oses the following convention to simplify the passing 
of nomeric inpgt. If a parameter evalgates to lass than 256, immediate 
mode Addressing is asaumed, otherwise direct memory mode is osed. 
Consi .ar th* following »xamples: 

POKE *2688,3 POKE *2008,30« 

expand to 

LDA #5 LDA 300 

STA *2000 STA *2000 

Eecaus* of these conventions, the programmer shoold be careful to 

avoid the following» which will prodgce ondesireable results: 

A) Calling ToolKit macros with page 0 labels as Parameters. 

B) Reftrencing forward labels in macro calls. 

Natgrally, the ToolKit macros specifically designed for branching have 
no problem with forward referencing of the branch point. 

Thft MAC/4.? ToolKit Abbrevi ations 

v - a numeric parameter passed in a macro call. If v < 256 immediate mode 
addressing is assomed, otherwise direct mode addressing is gsed. 

str - literal ASCII data. For example: "THIS IS A STRING“. Remember: 
MAC/63 literal* require double quotes as delimiters. 

adr - used directly as a memory address. For example: 

DPOKE adr,v 

expands to 

LDA «v 
STA adr 
LDA *8 
STA adr+1 

if the value v is less than 256. 
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* " 4h * oumtric value of * label ls used. For exampl«: 

VPOKE adr,* 

expand» to 

LM #<# 

STA adr 
LOA #>» 

STA adr+1 

Supportino M •.crom 

Th» following macro« ar» used internal to th« ToolKit't coding but arc not 
considered part of th» ToolKit sine» th»y wtr» not designed for your ute. 
(You may ut» th»m at your own ritk if you r»ad and undarttand th«ir 
Operation».) 

PHY - tav» Y r»gi»t»r on stack 

PHX - tav» X register on stack 

PHR - tav« X and Y register on «tack 

PHY - pull Y regiater from stack 

PHX - pull X register frora stack 

PLR - pull X and Y register from stack 

PLDA - MAC/65 Version of IDAP 

PLDX - samt at PLDA «xc»pt load X r«gitt»r 

8GBT ~ load a literal ttring. 

CHAN - load X r»gi«t»r for IOCB channel 
BLT - branch if lass than 
BGT - branch if gr»at»r than 

Srror Codmm. 

Th» ToolKit routin»» gtntrat« a couple of th*ir own error Codes» Namely: 

SRROR i75 (*AF) - detectcd by PRINUH; indicates integer magnitud* it 
too large to ditplay in specified field width. 

SRROR 176 (*B«> - detected by BLOAD; indicate» file it not in binary 
formst. 

Pleate Not*: The commandt which follow are presented in alphabetic order 
by library. Thi» was done to facilitate uter referencing. 
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The routines in thi* file allow you io do many divers» Operation», »o well 
group and synopsiz» of all Df them for your convenience? 


firiphta» 

COLOR v - Td specify the color valut to bt u*»d by PLOT. 
DRAWTO vl,v2 - To draw a line. 

FILL v - To fiU a »cretn region. 

GR v - Similar io the BASIC GRAPHICS command. 

10CATB vl,v2,v3 - Similar iD BASIC's LOCATE. 

PLOT vl,v2 - Similar io BASIC'* PLOT. 

POS vl,v2 - Similar io BASIC'* POSITION. 

SHTCOLOR vi,v2,v3 - Similar to BASIC's SETCOLOR. 
TXTPOS vl,v2 - To pcsition the Cursor in the text window. 



CALC v - To begin a nath calculation. 

PIV v - To do division. 

K INUS v - To do subiraciion. 

UL v - To do multiplicaiion. 

PLUS v - To dD addiiion 

RND v - To generate a random number. 

STORE adr - To save the resull of a math calculation. 
DI NC adr - Two byt» increment. 

DDEC adr - Two byte decrement. 


BGET v,adr,# - To get data from an IOCB channel. 

BLOAD str - To load a binary fil». 

BPUT v,adr,tt - To put data to an IOCB channel. 

CLOSB v - To close an IOCB channel. 

CLS - To clear the screen, 

CR Cv3 - To output a RETURN to an IOCB channel. 
pET v,adr - To get one byte from an IOCB channel. 
IN1NUM v,adr - To get a record from an IOCB channel. 
INPUT v,adr - To get a record from an IOCB channel. 
OPEN vl,v2»v3,str - To open an IOCB channel. 

PRINT v,adr/*tr - To output records to an IOCB channel. 
PRINUM vl,adr,v2 - To print out an integer value. 

PUT vl,v2 - To put one byte to an IOCB channel. 


DOI vi,v2 - To begin a DO loop using the I counter. 

DOJ vi,v2 - To begin a DO loop using the J counter. 

DOK vi,v2 - To begin a DO loop using the K counter. 

GQSUB adr - To preserve the X & Y registers when doing a JSR. 
IFEQ vi,v2iadr - Equality test. 

IFGT vl,v2,adr - Greater than test. 

IFLT vi»v2,adr - Less than test. 
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IFNB vl,v2,adr - Inequality test. 

LOOPI - Denotes and of DOI loop. 

LOOPJ - Denotes tnd of DOJ loop. 

LOOPK - Denotes cnd of DOK loop. 

TRAP adr - Similar to BASIC'* TRAP. 

JütaüiDtflm 

BCLR adr»« - To zero a spacific numbar of bytas in RAM. 

BMOVB adrl,adr2,# - To mova a mamory block. 

DINC adr - To do a two-byta jncramarvt. 

DPOKB adr»v - Do a two byta mamory pokt low byta first. 

POCLR v » To zarD a mamory paga. 

POMOVH v|,v2 - To mova a mamory paga, 

POKB adr»v - Pokes one byta into RAH. 

SOUND vi,v2,v3,v4 - Similar to BASIC'* SOUND. 

STOP - Dabugging aid to stop program execution. 

VPOKB adr,# - Pokes tha two byta numaric valua of a label or 
expression into mamory low byta first. 

WAIT v - To perform a time delay. 

And now for tha descriptions of tha macros thamsalvas. Thay hava bean 
alphabatizad for your convanienca. 


BCLR adr.# 

Purpose: To set a specific number of bytas in RAM to zaro. 

Params: adr - address of first byta to claar, 

# - numbar of consacutiva byta* to claar. 

Bxampla: Claar 1090 bytas starting at location HERB: 

1000 HERE «-*«1800 

9000 BCLR HERE,1000 


BOBT YlltfM 

Purpose: Gats a numbar of bytas from a devica opened on a spacifiad 
channal and storas tha bytas at tha mamory buffer spacified. 

Params: v - channal numbar to get bytas from 

adr - address of first byta of mamory buffar 
# - numbar of bytas to gat 

Bxampla: Get 3000 bytas from channal i and stör« in BUFFER 
1000 BUFFER «—*«5000 


9000 


BGET 1,BUFFER,5600 
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glOAP tlr 

Purpost: Loads a binary lila into memory from th* spacified davica 
using IOCB channtl 5. Caution: BLOAD can causa a 411* io 
load on top of your currently executing programi usually 
causing a System crash« unlass you ara careful about tha 
address rangas in use. 

Params: str - davica specification 

Bxampla: load an objact fila into memory: 

1898 BLOAD 'DiFlLE.OBJ* 


BHPVS adrl.adr2.8 

Purpose: Hoves a spacified numbar of bytes from one memory location 
to anothar. 

Params: adrl - address of first sourca byta. 

adr2 - address of first destination byta. 

8 - numbar cf bytes to move. 

Bxampla: Move 5988 bytes from FROM buffar to TO buffer. 

1888 FROH «**+5888 

1810 TO «*«+5908 

9888 BMGVE FR0H,T0,5088 


BPUT Viadr <8 

Purpose: PUT a numbar of bytes from a spacified buffer to a davica 
opened on a spacified channel 

Params: v - channel numbar to PUT bytes to. 

adr - address of first byte of memory buffer. 

8 - numbar of bytes to PUT 

Bxampla: PUT 5808 bytes from BUFFSR to channel i. 

1888 BUFFER a*e+5888 


9888 


BPUT 1,BUFFER,5808 
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CALCv 


Purpost: Bfgin i m*th cilculition by loiding FR« 

(dtcimil locition 212) with . two bytt inttgtr vilut. 

Papi ms: v - vilut U <25 6 or m.mory to loid FR« fron. 

‘“1S»;.J, h ,‘! 5 ,* h ° W * *“ ">*«' «««.. RBSULT 

leie RESULT .WORD 0 


3009 

3910 

3028 

3830 

3040 

3050 

3040 


tSOLVE EOUATION & STORE AT RESULT 
CALC 25 
MUL 30 
DIV 10 
PLUS 200 
MINUS 50 
STORE RESULT 


CLOSB v 

Purpost: To dos» in IOCB chinntl. 
Pirims: v - chinntl numbsr to clost. 
Bximplt: Clost chinntl 1 : 

CLOSE 1 

SU 


Pun>oi*5 To dtir tht scrttn. 
Pirims: NONE 


CPLQRv 

Purpost. Sptcifiis tht color vilut to bt ustd by PLOT TM« 4 
llmilir to (h. BASIC commind COLOR ‘ ™* m * Cro “ 

Pirims: v - Color rtgistcr ustd by PLOT. 

Bximplt: 


1010 


COLOR 1 
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CP Jr J 

Purpos»: To output a RETURN to an JOCB channel. 

Param*: Cv3 - optional channtl number. If no channel it specified, a 
RETURN is output to channcl 8 . 


EBBE »flr 

Purpo»»: To decrement a two-byt» valu». 

Param«: adr - address of th» two-byt* valu» to dccrtmcnt. 


PI NC adr 

Purpos»: To increment a two-byt* valu». 

Param*: adr - address of the two-byt» valu* to increment. 


DIVv 

Purpo»»: Divides th» two byt« integer currently at FR« by th» valu» 
given. Th* quotient is a one byt» integer left at FR«. FR0+1 
will be set to « and th* remainder will be left at FR1 <»224 
decimal). 

Param»: v - divisor 

Exampl*: See CAIC example. 


P Qi . 

Purpo»»: Begint a loop using the two-byt» memory location labeled I 
as th» counter. 1 will ränge from the first integer value given 
to the last and will always Ute a step value of 1 . 

Param*: vl - starting value of 1 

v 2 - valu* of I at which to terminat* the loop. 

Exampl»: Emulat* the BASIC command FOR 1*START TO END STEP i: 
1018 START .WORD 0 
1020 END .WORD 0 


3030 


DOI START,END 
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BOJ YliY? 


Purpos«: Bagint * loop uting th» two-byt» m»mory location lab»led J 
4« th» count»r. J will ring» fron ih» firtt 
int»g»r vilu» giv»n to th» latt and will always u«t « it»p 
vilu» 0 f 1. 

Pinnt: vl - atarting vilu» of J 

v2 - vilu» o* J at which to ttrminat» th» loop. 

Bxanpl»: Bmulat» th» BASIC command FOR J*BTART TO BND STBP 1: 

101# START .WORD 0 

1020 END .MORD 0 

3130 DOJ START,END 


DOK vl.v2 

Purpot»: B»gint 4 loop utlng th» two-byt» m»mory location labclad K 
at th» countcr. K will rang» from th» first int»g»r vaiu» 
giv»n to th» last and will always ut» a ft»p valu» of 1, 

Parasit: vi - starting valu» of K 

v2 - valu» of K at which to tarminat» th* loop. 

Bxanpl«: Bmulat» th» BASIC command FOR K«7 TO 25 STBP 1: 

1810 DOK 7,25 


PPQ8B idfax 

Purpot»: Do a two byt» m*mory poK», low byt» first. 

Parasit: adr - mcmory addrctt to poK» low byt». 

v - valu» il < 25Ä or addratt of firtt byt» of toure» tntmory 
word. 

Bxanpl»: Mov» th* ditplay litt polntcr to pag» 0: 

1010 D1SPL - 566 

1020 FR0 - 212 

1038 DPOKE FR0.DISPL 


Not»: Alto t»» VPOKE. 



Pag# 1* 


M AC/63 ToolKit v«r 1.M 


PPAWT0vl.v2 

Purpot#: Draw * lin# uting th# mort r»c#nt COLOR trom th# current 
tcr##n Cursor potitlon to th* terttn Position tp#cifi#d. Thit 
command is timilar to th# BASIC command DRAWTO. 

Paramt: vl - horizontal coordinat#. 
v 2 - vcrtical coordinat«. 


Bxampl#: 


1816 


DRAWTO IS,33 


E.1 H , y 

Purpot«: Fill terten with speeititd color. 

Paramt: v - color valu# 

Exampl«: Emulat* BASIC FILL program from pag# 54 of th# Atari 
BASIC rcfcrencc manual: 


1010 

GR 3«16 

1020 

COLOR 3 

103» 

PLOT 70,43 

1640 

DRAWTO 50,10 

1030 

DRAWTO 30,10 

1860 

POS 18,45 

1060 

FILL 3 


OST v«adr 

Purpot»: G#t# on# byt# trom dcvic» opened on tp«cifi»d channcl and 
stör# at ffltmory location tpteified. 

Paramt: v - Chan numbtr to get input byt» ■from. 
adr - memory addrats to stör# byt#. 

G«t 1 byt# from channcl 6 and tave byt# at mtmory location 


Exampl#: 

TEHP: 


1018 


GET 6,TEMP 
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QQ8UB adr 

Purpost: Prtstrvts tht X 4 Y rtgi.ttrs whiit »Hing « subroutint 
Params: idr - addrts» ot subroutint. 

Sxamplt: Call CIO: 

1818 CIO m SE456 
1828 Q0SU9 CIO 


fiß_K 


Purpou: Op.n. th. «r..n with th. .p.cifi,d gr.phic. mod.. TM. 
mtcro is slmilar to tht BASIC GRAPHICS command. 

Params: v - graphics mDdt (samt as in BASIC). 

Sxamplt: 


1818 


6R 7 


IFBQ vl.v2.afr 

Purpo ” SCC in, *»* r * * nd 6r “ ch " to 

Params: vi - ist inttgtr 
v2 - 2nd inttgtr 
»dr - addrtss to jump to 

Sxamplt: Jump to QUIT if ANS* 1888: 

1818 TI .WORD 1888 

18» ANS .WORD 8 


3888 

3818 

3828 QUIT 


IFEQ ANS,TI,QUIT 
STOP 
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I£gT.ytiX2iitfr 

Purpose: Branchts to address givtn if Ist integer is greller than tha 
2nd integer. 

Parasit: vl - ist Inttgcr 
v2 - 2nd integer 
adr - address to jump to 

Bxampla: Branch if COUNT>LIMIT: 

1818 LIMIT - 25888 

1828 TEMP .WORD 8 
1848 COUNT .WORD 8 

3818 VPQKE TEHP,LIMIT 

3828 IF6T COUNT,LIMIT,QüIT 

3838 STOP 

3048 QUIT 

Note: Sine» LIMIT is not a mamory address and is >236 wc must first 
pokt its actual valuc into th* mamory addrass TEMP for IFGT to worK 
proparly. If we did not do this» IFGT would compara COUNT to tha 
two-byta intagar at mamory location 23080. 


IHT YliYZiitfr 

Purpost: Branch to addrass givan if tha Ist two-byta intagar is lass 
than tha 2nd two-byta intagar 

Parasit: vl - ist intagar 
v2 - 2nd intagar 
adr - branch addrass 

Bxampla: Branch to QUIT H COLTNT<25: 

1818 COUNT .WORD 0 
1028 IFLT COUNT,25,QUIT 

1830 BRK 

1848 QUIT 


Purposa: Samt as IFEQ axcapt now branch if not aqual. 

Params: vl - ist intagar 
v2 - 2nd intagar 
adr - branch address 




Bxampla: Saa IFEQ axampla: 
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IMINUM v.adr 

Pupp°*t : Otts * lint from tha da vice optntd on tha aptcifitd channel 
thtn coiw.rU tha atring to a two-byta integer and «tor«« iJ 
in tha aptcifitd mtmory location low byta fjp*t. 

Parans: v - channcl « to gat lin« from 

adr - addraaa to ctorr intagar valua at 

Bxamplt: Gat a number from tha aditor and stört in TEMP: 
i>18 TEMP .WORD 8 


3888 


ININUi 8.TEMP 


IHftfT vtttfr 

Purp0,,: * rom * d « vi « °P»"»d tha aptcifitd channel and 

ttoras lt in aptcifitd mtmory bufftr 

Parama: v - channal # to gat lint from 
adr - addraas to atora lint at 


Bxamplt: Gat racord from aditor and atora in BUFFER: 
1818 BUFFER *-««234 

3*18 INPUT 8,BUFFER 


LQCATB vl.v7.v3 


Purpoat: 


Gata a byta from tha apaciflad acrtan location and 
atoraa it in tha aptcifitd mtmory location. Thia macro 
la aimilar to tha BASIC command LOCATB. 


Parama: vl - horizontal acraan location 
v2 - vartical acraan location 
v3 - addraaa to atora byta 


Bxamplt: Gat byta at 5,5 and störe in TEMP: 

1818 TEMP .BYTE 8 


3888 


LQCATE 5,5,TEMP 
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LQQPI 

Purpott: P*rformt th» ttm« functlon a th» BASIC commtnd NSXT I 
P tränt: NONE 

Bxtmpl*: D*t«rmin* thc tun of th» numbcrt 1 - 1# tnd itor» tt 
RBSUIT: 

1010 RESULT .WORD B 

3020 *CALC B 

3038 DOI 1,18 

3140 PLUS I 

3BSB LOOPI 

3BdB STORE RESULT 


LQQ Ti 

Purpot»: Stm» tt LOOPI, but for th» J count»r. 
Ptrtmt: NONE 
Bxtmpl»: S»c LOOPI. 


LP PPK 

PurpDt»: Stm» tt LOOPI, but for th» K counttr. 
Ptrtmt: NONE 
Bxtmpl«: S»» LOOPI. 


H JJWg Y 

Purpot»: Subtrtct» t two byt» int»g»r from th» two byt» int»g»r 
currtntly tt FR« tnd l»tv»t th» r»tult tt FR«. 

Ptrtmt: v - vtlu» if <25d or mtmory locttion to find vtlu» 
to »ubtrtct from FR«. 


Bxtmpl»: S«» CALC »xtmplc. 
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MÜL Y 

Ptrpos*: Multipli» s th» on* byt» valu» givtn by 1h» on» byt» valu» 
locattd «1 FH«. Th» rtsult is a two byt» int»g»r Urft at FR». 

Parans: v - valut if <254 or m»mory location of multipliar. 

Exanpl«: Bat CALC »xampl». 


QPEN vl.v2.v3.slp 

Pirpos»: Opans a d»vic» on an IOCB channtl. This macro ptrforms 1h» 
sam» function as 1h» BASIC OPEN command. 

Para ms: vi - IOCB channtl Io op*n 
v2 - AUX1 
v3 - AUX2 

StP - davic» sptcification 

Exanpl»: Opan th» RECORDER on channtl 1 for short gap output: 

II!« 0POI 1, 8 ,1 28 , * C i ■ 


EflCLfi Y 

Purpos»: S*1s a spacificd pag» of HAH to z»ro 

Parans: v - numb»r of 1h» pag» Io cl»ar. 

Exanpl»: Clcar pag» 4: 

111« PGCLR 4 


POMOVE vl.v2 

Purpos»: Mov»s a pag» (254 bytcs) of mcmory from one pag» to another 

Params: vl - sourc» pag» numbtr. 

v2 * dtstination pag» numbtr. 

Exanpl«: Movcs th» byt»» of pag» 54 to pag» 4: 

1811 PGMOWE 54,4 

Not*: This routin» works much fast»r than BHOVE. 
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ELQ T yI .yZ 

Purpo*t: Plot* * point on tht scr»*n at th* sp»cifi»d location u*ing 
th» color r*gi»t»r »p»cifi»d in th» most p»c»nt COLOR 
com m and. 

Par am»: vi - horizontal coordimt» 
v2 - vertical coordinat» 


Sxtmpl»: 


1810 


PLOT 3,7 


PLUS v 

Purpo*»: P»rform* a two byt* int*g»r addition of th» valu» giv»n with 
th» two byt» int»g»r valu» now at FR». Th» r»*ulting »um i* 
l*ft at FR». 

Params: v - valu* if <256 or m»mory location to find valu» to add to 
FRO. 

Sxampl»: Sei CALC »Kample. 


PQKB adr.v 

Purpo»»: Poket onc byt» into RAH 

Params: adr - m»mory location to pok» byt» 

v - valu» if <256 or memory location of sourc» byt» 

Sxampl«: S*t th» top of RAM at 32K boundary: 

1010 RAWTOP - 106 

1020 PORE RAMTOP,128 


PQS vl.v2 

Purpo»»: Position» th» scr»»n Cursor. Thi» macro is similar to th» 
BASIC POSITION command. 

Param»: vl - horizontal coordinat» 
v2 - v»rtical coordinat* 

Bxampl«: Position Cursor at x*5»y*10: 

101» POS 3,10 
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FBIHT YtitirWr 

Purpost: Print rtcord* output to a sptcifitd channtl. Th* output 
rtcord can bt optionally a Uttral String (* hallo' ) or from a 
mtmory bufftr. NOTE: PRINT always Outputs an BOL ($9B) at 
tht tnd of tach rtcord. If no EOL is dtttcttd in an output 
string tht ltngth dffault* to 255 bytts. 

Par «ms: v - channtl numbtr to output rtcord to 

adr/str - addrtss of mtmory bufftr or a littral string 

Bxamplt: Print HELLO on tht scrttn: 

1910 {USIN6 LITERAL STRINS 

1020 PRINT 4,"HELLO" 

1010 jFROM MEMORY 

1928 STR .BYTE "HELLO",*?B 

3810 PRINT 4,STR 


ERIHUH YhitiriYZ 

Purpost: To print out an inttgtr of a givtn ltngth to a specifitd 
channtl» 

Parins: vl - tht IOCB channtl 

adr - tht addrtss of tht inttgtr 

v 2 - tht width of tht numbtr in characttrs. 

Bxamplt: 

1008 PRINUN 8,MALAOR,9 


FVTYl.Y? 

Purpost: Puts a 1 bytt valut to dtvict optntd on sptcifitd channtl. 

Parins: vl - channtl numbtr to PUT bytt to 

v2 - valut or ment addrtss of bytt to PUT 

Bxamplt: PUT bytt from TB MP to dtvict on channtl 1: 

1910 PUT 1 ,TEMP 
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RHD v 

Purpoa«: Gvncrat» a random tt Un than th* »p*cifi*d valu» (which 
mu»4 b» <250 and ltav» th* random numbtr in th» 
accunulator. 

Parana: v - Random numbtr will bt l*»a than thia valu». 

Bxampl«: G»n»rat* a di» roll 1-6 and ator» in DIB: 

ISIS DIE .BYTE 0 

9880 "‘MD 6 

9110 CLC 

9028 ADO »1 

9030 STA DIE 


SBTCQLORvl.v2.v3 

Purpoa*: Scta th» »pccifiad color r*gi*t»r to th» spacifitd color hu» 
and luminanc» valu*». Thi» macro is 
aimilar to th» BASIC command SBTCOLOR. 

Parana: vi - color r»giat»r 
v2 - color hu* 
v3 - color luminanc» 

Bxampl»: S*t bordar color to whit*: 

1010 SETCOLOR 4,0,14 


SQUHB y1.y2.y3.y1 

Purpoa»: Play» a aound of a »pccificd pitch, diatortion and volum» 
uaing th» apccifitd voic». Thi* macro i* aimilar to th» BASIC 
command SOUND. 

Parana: vi - voic* (0-3) 
v2 - pitch (0-255) 
v3 - diatortion (0-14) 
v4 - volum» (0-15) 


Bxampl»: 


1010 


SOUND 2.204.18.12 
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STOP 

Purpou: Debugging aid: «ounds a Ion* and then weit» for th* START 
k*y io b* pr****d betör* coniinuing *x*cuiion. 

Parana: NONS 

Bxampl«: 

1910 STOP 


8TPRB itfr 

Purpoa»; Sior** ih* iwo bytea »iarting at FR0(=2I2> to a apecitied 
addr*aa. Thi» macro is uaually uaed io aior* ih* r**ult of a 
maih calculaiion eine* ih* maih functiona uae FR». 

Para«*: adr - addreaa to aior* two byt*a now ai FR« & FR0+1. 

Bxampl»: S*» CALC «xampl*. 


TBAP adr 

Purpos»: Stic addreaa to which program *xecution will jump if an *rror 
ia d*i*ct*d (uaually an I/O error). It ia ia initialized iD jump 
io QQBRR which ia pari of ih* ToolKii'a objeci code. QQERR 
will prini ih* ERROR numb#r on ih* acreen and ihen do a 
SYSTEM RESET. 

Parama: adr - addreaa io jump io on *rror 

Bxampl*: Break io moniior on an error: 

1019 QUIT STOP 

3018 TRAP QUIT 


IfffP S y I iy Z 

Purpc**: Position* ih# Cursor in ihe iexi window whil* in a aplii 
screen mode. 

Parana: vi - horizontal coordinaie 
v2 - vertical coordinaie 


Bxampl»: 


1010 


TXTPOS 25,2 
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VPQKB ttfril 

Purpou: Poktt th« two byt» numaric valu« of a labal or «xprettion 
into m*mory low byt« «rat. 

Para»»: adr - mtmory location to pok« low byt«. 
tt - labal whot« valu« will b« poK»d. 

Bxaatpl«: Pok« th« numb«r 29ttt into RAH location 56t: 

Itlt VPOKE 566,29159 


WAlTv 

Purpoa«: Perform» a tim» dclay. Th« tim« wait »quält th« valu« giv»n 
timet i/6tth of a tacond. 

Paramt: v - number of jiffie» (l/6tth of a tecond) to w*it. 

Bxampl«: Do nothing for 1 tacond: 

1911 MAIT 69 
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PMQR.M65 

iht routincs ln this fil# illow you to tritt# And mov# pltyirs ind mistili* 
uilna i virticil blink routini, •« will ai chick for collision*. Th# 
following i» a tynopsis Df th« microt: 

MMOVB vl«v2,v3 - Movis a mistili 

MPFC vl,v2 - Miitili to Pliyfiild colliiion tut 

MPLC vl,v2 - Hiliil# to Pliyir colliiion tut 

K8IZB vliv2»v3 - Sit hiight & width of miisilt 

PLPFC vl*v2 - Pliyir to Pliyfiild colliiion tut 

PLPLC vl*v2 - Pliyir to Pliyir colliiion tut 

PMCOLR vl t v2iv3 - Siti pliyir/mitsil# color 

PMOR v - litt up tingli lim molution pUyir/miiiili griphici 

PHMOVB vl,v2,v3 - Movis i pliyir 

PSJZB vl,v2,v3 - Sit* height tnd width of pliyir 

SSTVBC Adr - Chingn th# iddriu th# pliyir/missli virticil blink 
intirrupt routin# ixits to. 

SHAPB v,idr - Till# th# pliyir movemmt routin# th# iddriu of th# 
firit byt# of pliyir ihipi diti 


HMQVB vl.v2.v3 

Purpoi#: Movn mistili to spicifiid poiiton on scrim 

Firnis: vi - mistili « (0-3) 

v2 - horizontil coordimt# 
v3 - virticil coordinit# 

Sximpli: 

1010 tflOWE 0,125,125 


HPFC vt.y l 

Purpot#: Chicki if a colliiion hu occurrid bitwun i spicifiid mistili 
number And pliyfiild numbir. Th# ziro fl*g is t#t jf NO 
colliiion hu occurrid. 

Pirims: vl - mini# numbir (0-3) 

v2 - pliyfiild numbir (0-3) 

BMinplt: Jump to KILL routin# if colliiion occurs: 

1010 MPFC 2,1 

1020 GNE KILL 
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ü£l£.Y,id2 

Purpott: Chtckt if • collition hat occurrtd bttwttn * tptcifitd mittilt 
numbtr and playtr numbtr. Th# z#ro flag it ttt if NO 
collition hat occurrtd. 

Paramt: vl - mittlt numbtr (6-31 
v2 - playtr numbtr 16-3) 

Bxamplt: Jump to KILL routint if collition occurt: 

1010 MPLC 2,1 

1020 BNE KILL 


WSi»Yl.Y^Y9 

Purpott: Stt htight 0 width of mittilt 

Paramt: vl - mittilt numbtr 

v2 - mittilt width (l-tingl*, 2»doublt, 4»quad) 
v3 - mittilt htight in tcrttn lintt 

Bxamplt: Stt mittlt 2 to normal width and 16 lintt high: 
1010 MSI2E 1,2,1« 


PL PFC y! .iy2 

Purpott: Chtck* if a collition hat occurrtd bttwttn a tptcifitd playtr 
numbtr and playfitld numbtr, Tht ztro flag it ttt if NO 
collition hat occurrtd. 

Paramt: vl - playtr numbtr (0-3) 

v2 - playfitld numbtr (0-3) 

Bxamplt: Jump to KILL routint if collition occurt: 

1010 PLPFC 2,1 

1020 BNE KILL 
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ELflC yI.y? 

PurpoM: Checks if * collision has occurred between ipicifitd pUyer 
numbers. Tht zero tlag is set if NO collision has occurrtd. 

Paraais: vl - player number (0-3) 
v2 - player number (t-3) 

Bxanple: Jump to KILL routin» ii collision occurs: 

1113 PLPLC 2,1 

132t BNE KILL 


PHCOLR vl.v2.v3 

Purpos»; Sets player/missile color 

Params: vl - player number (t-3) 
v2 - color hu» 
v3 - color luminance 

Bxsmpl»: Set player 1 to gray: 

ltlt PHCOLR 1,0,8 


EHOBy 

Purpos«: This macro sets up singl» lin» resolution player-missile 
graphics st th« sp»cfi»d PMBASB. It «Iso inst*lls th* pl*y»r 
«nd missile movement routine to execute during th» verticsl 
blink Interrupt. 


Ptrams: v - RAM p*ge to set «s pliyer-missile base 

Extmple: Set PMBASB 16 pages below RAMTOP: 

ltlt RAMTOP » 106 

1020 BASE .BYTE 0 

3t10 ''SEC 

3«2t LDA RAMTOP 

3030 SBC Hl6 

3040 STA BASE 

3050 PMGR BASE 
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EMMflVB v >iy 2.y3 

Purpot«: Mov*a playtr to tp«cifi«d potition on scrvtn 

Param«: vl - playtr numbtr (4-3) 
v2 - horizontal coordinat« 
v3 - vtrtical coordinat« 


Bxampl«: 


1411 


PHOVE 4,125,125 


PSI« Yl.Y2.v3 

Purpot«: S*tt htight and width ot playtr 

Param«: vl - play«r numbtr 

v2 - play«r width U-tingl«, 2»doubl«, 4>quad>. 
v3 - playtr htight in tcr««n Unct 

Bxampl«: S«t play»r i to doubl« width and 14 linta high: 
1414 PS1ZE 1,2,14 


SETVBC adr 

Purpott: Changtt th« addrtt« th« playtr/mittl« vtrtical blank 
inttrrupt routin« cxitt to. At tatup, th« playtr/mittl« 
v«rtical blank routin« «xitt to th« ROM routin« XITVBV iexit 
v«rtical blank inttrrupt) at 4E462. 

Param«: adr - addrtt« to «xit to 

Bxampl«: Inttall routin« DONOTH1NO to »xacut« during VB1: 

1414 SETVEC DONOTHING 

9444 DONOTHINß 

9414 JMP XITVBV 
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SHAPB v.idr 

Purpo*»: Teilt th# player movement routin# the address of th# first 
byt# of player tbap# data 

Paraas: v - player number <8-3> 
adr - address of data 

Bxample: Alternat# shape of player i: 

1821 LOOP SHAPE 1,P1CTURE1 
1838 UAIT 15 

1848 SHAPE 1,PICTURE2 

1858 UAIT 15 

1868 JHP LOOP 
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u»ina th* SCRQLL.M65 Library 

Th» Scroll library Controls fine Scrolling and is a littl* mor» complicated 
than th» othtr librarits. ln addition to macro calls for dimtnsioning a 
Scrolling display, th» us»r Controls th» speed and dircction of th» scroll 
by a direct memory pok», The memory locations which a programmer may 
wish to us* ar» explained in this section. Th»s» locations ar» id*ntifi»d 
by global labcls which ar» NOT prefixed by QQ. 

You do not n«»d to understand th» details of fint scrolling as th» routines 
in SCROLL.M43 manag» this complex proc*ss for you. Therfor«, this 
mangal do»s not attempt to tutor you on this subject. Th» int*r»st»d 
r»ad»r is r»f»rr»d to De R« Atari and to a series beginning in th» Octoberi 
1983 issu« of ANALOG magazin» for mor« Information on fin» scrolling. 

aCRQLL. Mtmgrv LacAtlgni 

Th* SCROLL.M45 macro SCRDIM installs a routin» to «xecut* as a deferred 
vtrtical blank interrupt routin». If you wish to hav» another routin» 
•xecut* as part of th* vertical blank interrupt protess, it must b» 
installed prior to using SCRDIH. SCRDIM saves th* address locatcd at th* 
deferred vertical blank interrupt vcctor at location dreimal 54$ and jumps 
to it when it has concluded its proc»ssing. After dimtnsioning your 
display using SCRDIM» th» only thing you must do to »xecut» fin» scrolling 
is to POKE th» proper location. 

PftfftgiitTri la. Ihi fflitttt Mi 

MODE - ANTIC mod» (2-7) Not*; SCRDIM always uscs th» split scr»»n 
mod*. 

XDIM - Enter th» horizontal dimension in characters of your »ntir» 
display. It must b» < 254. 

YDIN - Enter th» vertical dimension in characters of your »ntir» 
display. It must b» < 254. 

SCRBAS - th* address of th* first byte of display data. Som» care 
must b» taken in choosing this valu» sine» ANTIC will b* confused if 
any mod« lin* jumps over a 4K boundary. If your screcn display is less 
than or »quäl to 4K, placing th» scrcen on a 4K boundary will »liminate 
this problcm. If your serten is greater than 4K, you must choos» th» 
screcn address so that on» mode lin* ends and another begins precisely 
on a 4k' boundary. 

SDISPL - th» address at which you would lik« SCRDIM to write th« 
display list. Your only concern in choosing this valu» is that th» 
display list must not cross a 1K boundary. The maximum length display 
list is for mode 2, 4» and 4 and is 72 bytes long. 
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LMition» »»< by th* macro scrdim 

XiLIM - Horizontal right limit of fin» scrolling, 

YILIM - Vertical lower limit of fin* scrolling. 

XLOC - tht location which contains th# horizontal character coordinat* 
of th» upptr left corncr of th» display scr»*n. 

YLOC - th* location which contains th» vertical character coordinat» of 
th» upp»r l»ft corn»r of th* display screen. 

Loettion» not »tt bv scrdim 

SCROLL - th* location which Controls th* direction of th* fin» scroll. 
Th» numb*r you POKE her* is th» »am» number th» STICK«») BASIC 
function returns when th» Joystick is mov*d in that direction <i5*no 
scroll« 7*right to l*ft« ii*l*ft to right). Using this Convention allows 
you to »asily control a fin* scroll with a Joystick. 

VSPBSD - th» location which Controls th» vertical fin* scrolling speed. 
Do a POKE VSPEEDi» for th* fastest speed. Larger numbers will result 
in incrementally slowcr speeds. 

HSPSBD - th* location which Controls th» horizontal fine scrolling 

speed as abov». 


Th» following is an exampl* to do a continuous horizontal fin* scroll at 
maximum speed: 


1010 

POKE HSPEED 

1020 LI 

POKE SCROLL 

1030 

LDA XLOC 

1040 

CMP X0L1M 

1090 

BNE LI 

1040 

POKE XLOC.0 

1070 

JHP LI 


QlDtr lPc*tlon» »s»d bv th» s crollino routin»»: 

Th»s» location* should NOT b» modified by th* programmer! 


CSRBAS - Address of first byt» of current display 

SHSROL - Horizontal fin* scroll shadow registcr 

SVBROL - Vertical fin» scroll shadow registcr 

LINES - Internal variable 

JMPBYT ~ Internal variable 

RVBIV - Address through which SCRDIM »xits 

CWIDE - Character width in color clocks 

CHIOH - Character height in screen lines 

HLINBS - Internal variable 
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8RBYTW - Display scrttn width in bytts 
5DIR - Scroil dirtction shadow 
HCOUNT - Counttr Controlling horizontal spttd 
VCOUNT ** Countir Controlling vtrtical spttd 

OLDVBV - Hold* th» prtviou* valu* of th« vtrtical blank inttrrupt 
vtctor. 


8CRQLL.M65 M*cro» 

Thi* tili contain* two macros to tnablt fint tcrttn scrolling a* follows: 

SCRDIM vi,v2»v3,adrl,adr2 - S#t* fint scrolling paraaitttr*. 

SETXY vi»v2 - 5*ts up coarst boundarits for furthtr fint scrolling. 


SCRDIH vl.Y2.v8.adrl.adr2 

Purpo*#: Stts dimtnsion paramtttrs for fint scrolling (ui Using th» 
SCROLL.M65 Library). 

Params: vi - ANTIC modt (2-15) 

v2 - horizontal dimtsion of display «256) 
v3 - vtrtical dimtnsion of display «256) 
adrl - addrtss whtrt display list is writttn 
adr2 - addrtss of Ist bytt of display data 

Bxamplt: S*t up fint scrolling using ANTIC modt 7. Display sizt is 

64x64» 5CRBBN is 8K bytts from RAMTOP» and display list is in pagt 6: 

18 SCRDIM 7,64,64,4608 »IRT-323»256 


SETXY vl»v2 

Purpost: Dots a coarst scroil, Th* sptcifitd x,y cDordinatt» of th* 
tntir* display ar* plactd at th* upptr ltft corntr of th* 
scrttn. Not»: Whtn in th* fint scrolling modt, ANTIC 
ritritvts mor* bytts ptr lint than art displaytd on th* 
scrttn. Thtrtfort th* ltft tdgt of th* scrttn will bt slightly 
off thi ltft of thi visiblt scrttn. 

Params: vi - horizontal coordinat* 
v2 - vtrtical coordinat* 

Bxampl»: Movt display sttting ltft corntr at x«5,y«8: 

18 SETXY 5,8 


STPPSCfiQLl 


Purpost: Turns off th* fint scrolling vtrtical blank inttrrupt routint. 
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Thi» macro thould b* catled betöre exjting * program back to 
DOS. The »creen, however, ia not returned to a Standard 
graphics mode, to the macro Qfi thould alte be uted to change 
terttn modes betöre exitlng the program, 

Param«: NONB 

Bxample: 

1# 


STOPSCROLL 
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